Description

This operation entails performing an authorization code grant type OAuth 2.0 request or an OpenID Connect authentication request. In contrast to the other TRIDENT APIs, the messages of this operation are not exchanged directly between the client application and TRIDENT but rather indirectly via the user's browser using browser redirects.

This operation lets an application obtain authorization from the user for accessing one of their resources or their identity data. The user's authorization is obtained via an authorization code credential. The authorization code is sent via the browser as a response from the operation. The application exchanges the authorization code for the corresponding access token for accessing the resource (see Obtain a Token). In the case of OpenID Connect, when the authorization code is exchanged, an ID token is also obtained. The scope of the requested authorization (e.g., for accessing identity data, using signing identities, etc.) is specified in the request.

Request

To start the authorization code grant flow, the client application directs the user's browser to TRIDENT’s /trustedx-authserver/oauth/ endpoint. As a result of this redirect, the browser sends an HTTP request like the following to TRIDENT. This request is either an OAuth 2.0 authorization request or an OpenID Connect authentication request (depending on whether the scope includes the openid value). The request must be sent by TLS and use the GET or POST method.

Note

Suppose this operation is used to authenticate a user and access their identity data. In that case, it is recommended that the request be formatted as an OpenID Connect authentication request and, therefore, include the openeid value in the requested scope. In this case, it is also recommended to save the id_token parameter that will be later received in the response of the Obtain a Token operation so that it can be included as the value of the id_token_hint parameter in the request to Log out that will finally be carried out.

GET /trustedx-authserver/oauth?response_type=code&
                                    client_id=...& 
                                    state=...&
                                    nonce=...&
                                    redirect_uri=...&
                                    scope=...&
                                    prompt=...&
                                    acr_values=...&
                                    view_type=...&
                                    ui_locales=...&
                                    register_group_labels = ...&
                                    sign_identity_id = ...&
                                    num_signatures = ...&
                                    digests_summary = ...&
                                    digests_summary_algorithm = ...&
                                    authorization_details = ...&
                                    login_hint = ...&
                                    id_token_hint = ...

Note

All the applications integrated with TRIDENT via browser redirect (OAuth 2.0 or SAML 2.0) must do so using a consistent base URL that has the same DNS domain name, the same port (by default, 8082), and the same Web application name (by default, trustedx-authserver). The browsers must always connect to the TRIDENT using the same base address so the identity provider can consistently maintain the sessions and apply SSO.

Alternative Endpoints

It is also possible to redirect the browser to the /trustedx-authserver/oauth/{as} endpoint. However, this should only be done if the TRIDENT administrator has associated your application with several Authorization Servers that recognize all the values included in the scope field of the authorization request for Authorization Code Grant flows (which is an advanced scenario). In any other case, you should point the browser to the /trustedx-authserver/oauth endpoint.

On the other hand, to keep backward compatibility, you can also redirect the browser to the following endpoints:

/trustedx-authserver/{as}/oauth
/trustedx-authserver/{idp}/oauth/{as}

Remember that these two endpoints should never be used for new integrations as they are supported only to prevent legacy integrations from breaking down, and supporting them may be terminated in the future.

Parameters

Name	Type	Usage	Description
`as`	path	Optional. It should only be used if the application is associated with more than one Authorization server that supports the requested scope for Authorization Code Grant flows.	Identifier of the TRIDENT authorization server to which the authorization request is sent (Server ID field of one of the Authorization server entities). When this parameter is not specified, the TRIDENT automatically selects the authorization server, choosing the one associated with the application and supporting Authorization Code Grant for the requested scope (for all values it includes). If none of them meet this condition, or if several of them meet this condition, the TRIDENT will cancel the authorization by displaying an error in the user's browser (see Error Management ).
`idp`	path	Optional (it can only be present when the `as` parameter is also present ).	Identifier of the identity provider associated with the authorization server indicated by the `as` parameter.
`request_uri`	query	Optional. Must only be used if the content (payload) of the authorization request was sent directly to the TRIDENT via the Push an Authorization Request operation	One-time URI for an authorization request previously sent to the TRIDENT via the Push an Authorization Request operation.
`response_type`	query	Required	Must take the `code` value, which indicates that an authorization code is requested.
`client_id`	query	Required	Identifier of the OAuth 2.0 application registered in TRIDENT (Client identifier field of one of the Client application entities). The application must be associated with the authorization server and have the use of the authorization code grant enabled.
`code_challenge`	query	Recommended, as it protects against theft of the authorization code sent to the application in the response.	Value calculated from the `code_verifier` parameter that must be included in the subsequent request to the Obtain a Token operation (see [RFC 7636]).
`code_challenge_method`	query	Conditionally required	Method used to calculate the `code_challange` parameter's value from the value that is to be put in the `code_verifier` parameter of the subsequent request to the Obtain a Token operation. This parameter is required if the `code_challenge` parameter is used. The only value supported is `"S256"`. This means that the `code_challenge` value is obtained by calculating `base64url_encode(SHA-256(ASCII(code_verifier))))`, where `code_verifier` is a high-entropy random string between 43 and 128 characters (see [RFC 7636]).
`state`	query	Recommended	We recommend using this parameter to safeguard against CSRF attacks. To do this, the application must include a random value in this parameter, store it in the HTTP session, and verify it when the Authorization Response message is received. The random value associates the authorization request with the HTTP session, which safeguards against the application processing an Authorization Response message not returned in response to an Authorization Request message specified previously in the user's browser. The application can also include additional information in this parameter, such as the URL to which the browser will be redirected when the OAuth flow finishes. (To include multiple data in the value of this parameter, the application must serialize it as it sees fit.)
`nonce`	query	Recommended in OpenID Connect requests	We recommend using this parameter in OpenID Connect authentication requests to safeguard against replay attacks on obtaining the ID token. For this, the application must include a random value in this parameter (taken from a space with sufficient entropy so that an attacker cannot guess it), store it in the HTTP session, and, later on, when it obtains the ID token, check that it matches the nonce claim of the ID token. This random value associates the authentication request with the ID token issued, safeguarding against an attacker using an ID token previously captured from another user and resending it to the application.
`redirect_uri`	query	Conditionally Required	Redirection URI to the application. The application waits to receive the Authorization/Authentication response message with the authorization code at this URI. It must be one of the redirect URIs registered for the client application or a redirect URI of the system. This parameter can be omitted if only one redirect URI was registered for the application. In this case, the registered redirect URI is used. This parameter can also be omitted if the authorization request references, via the `request_uri` parameter, an authorization request previously pushed to the TRIDENT without going through the user agent.
`scope`	query	Optional	List of values, separated by spaces, that represent the scope of the authorization the application wants to obtain. Check with the TRIDENT administrator about the scopes needed to access the different resources and services. To request an OpenID Connect authentication, the application must include the `openid` scope value in this parameter. If this parameter is not specified, the default scopes defined for the authorization server with authorization code grant enabled are taken.
`prompt`	query	Optional	The values `login` and `none` are supported: The `login` value disables SSO. The `none` value specifies that there can be no interaction with the user (neither for authenticating them nor for requesting their authorization). See [RSE_AUTH_INTEG] for more information.
`acr_values`	query	Optional	Defines conditions for authenticating the user (minimum levels or specific flows) who must authorize the access. See [RSE_AUTH_INTEG].
`view_type`	query	Optional	This is a nonstandard parameter for requesting a particular visualization format for the user interfaces displayed to authenticate the user and obtain their consent. See [RSE_AUTH_INTEG].
`ui_locales`	query	Optional	Specifies a list of languages ordered by preference. TRIDENT uses this list to select the language for displaying the graphical interfaces for authenticating users and obtaining their consent. The value of this parameter is a list of language labels, as per RFC 5646, separated by spaces. The interface is displayed internationalized according to the first label in the list whose base language is supported by the TRIDENT or has been customized. For how to customize a language, including country, dialect, identity provider, and/or `view_type` value variants, see [RSE_AUTH_INTEG]. This parameter is optional. If this parameter is not included (or it is, but it specifies an unsupported language), the language specified by the browser is used, and if this language is not supported, US English is used (en-US).
`register_group_labels`	query	Conditionally Required	This parameter is required to get the user's authorization to create server-signing identities whose activation is through the SAM or an HSM-validated password. Otherwise, it is optional. Its value must be the list of labels that identify the identity's registration group—that is, as much the schema labels as the registration group labels. Note Generally speaking, dynamic labels shouldn't be used to identify a group. Nevertheless, if they are indeed used for this aim, you must only include their name (not their value) in the `register_group_labels` parameter value. See the Authorization section of the create a signing identity and its associated keys on the server and create the issue process for a signing identity group operations.
`sign_identity_id`	query	Optional. It can't be present when the `authorization_details` parameter is used.	This parameter must only be used to obtain authorization from the user for generating a digital signature with a server signing identity enabled via password stored on the HSM or for changing the password value that protects an identity of this type. See the Authorization section of the create a digital signature on the server operation and the Authorization section of the update the enabling password of a server signing identity in the HSM operation for more details.
`num_signatures`	query	Optional. It can't be present when the `authorization_details` parameter is used.	The number of signatures whose generation the user must authorize. This parameter can only be present if the `sign_identity_id` parameter is also present (otherwise, the TRIDENT will ignore the `num_signatures` parameter). If the user grants authorization, the access token obtained later can only be used to generate `num_signatures signatures` at most, and it can only be used once. The value entered must be equal to or less than the value configured by the TRIDENT administrator in the Signature Provider. Check with your administrator if you need to know this value.
`digests_summary`	query	Optional. It can't be present when the `authorization_details` parameter is used.	This parameter must only be used to obtain user authorization for generating a digital signature (or a batch of digital signatures) with a server signing identity activated with a password stored on the HSM. Its value must be the base64 encoded cryptographic hash of the concatenation of the data and cryptographic hashes to be used to create the digital signatures. This concatenation must be done in the same order and with the same data and cryptographic hashes as those specified subsequently in the request for generating the signature (see Create a Digital Signature on the Server and Create a Digital Signature Batch on the Server).
`digests_summary_algorithm`	query	Optional. It can't be present when the `authorization_details` parameter is used.	This parameter must only be used to obtain user authorization for generating a digital signature (or a batch of digital signatures) with a server signing identity activated with a password stored on the HSM. Its value ("`sha256`", "`sha384`" or "`sha512`") must be the algorithm for obtaining the cryptographic hash specified in the `digests_summary` parameter.
`authorization_details`	query	Optional. It can't be present when the `sign_identity_id`, `num_signatures`, `digests_summary` and `digests_summary_algorithm` parameters are used. If you need this parameter, sending it with the Push an Authorization Request operation is better.	Detailed information regarding the requested authorization (see[RFC 9396]). Currently, details provided can only refer to the generation of one or more signatures with a given signature key. This property's value is obtained by encoding the following JSON object with `application/x-www-form-urlencoded` method (keeping in mind that the first-level array must contain just one element): `[` `{` `"type": "digest_signing",` `"sign_identity_id": {string},` `"num_signatures": {number},` `"digests": [` `{` `"value": {string},` `"algorithm": {string}` `}` `]` `}` `]` donde: `sign_identity_id`: identifier of the signing identity to generate one or more signatures for which authorization is requested. It is mandatory that this signing identity's activation is with an HSM password or through the SAM. `num_signatures`: number of signatures to generate using the signing identity indicated by the `sign_identity_id` property. `digests[]`: Hashes of the data to sign. It must have one element at least. `digests[].value:` The hash of one piece of data to sign. `digests[].algorithm:` (Optional) The algorithm used to generate the hash of one piece of data to sign: "`sha256`", "`sha384`" o "`sha512"`.
`login_hint`	query	Optional	Suggested user identifier that can be used if the user must be authenticated.
`id_token_hint`	query	Optional	ID Token provided by TRIDENT when it authenticated (using OpenID Connect) the user whose authorization is now wanted. If the TRIDENT has to authenticate the user again (e.g., because the user's session expired), the user identifier obtained as a result of this authentication must match the one that appears in the `sub` claim of the ID Token provided in this parameter.

Example: Authorization Request

This example shows an OAuth 2.0 authorization request message from the demoapp application.vThe application requests an authorization with the urn:safelayer:eidas:sign:identity:use:server scope (use of the server signing identities of the user) and specifies that it expects the authorization code at the https://www.demoapp.com/oauth/back redirect URI. The user's browser made this HTTP request due to a redirect from the application. Ellipses and line breaks have been included to facilitate reading.

GET /trustedx-authserver/oauth?response_type=code&
                               client_id=demoapp&
                               scope=urn%3Asafelayer%3Aeidas%3Asign%3Aidentity%3Ause%3Aserver&
                               state=IxtdZtOguYVF&
                               redirect_uri=https%3A%2F%2Fwww.demoapp.com%2Foauth%2Fback HTTP/1.1
Host: trustedx.demo.com:8082

Example: OpenID Connect Authentication Request

This example shows an OpenID Connect authentication request message from the demoapp application. The application requests an authorization with a scope described by the profile, email and openid values (this last value specifies that it is an OpenID Connect request). The application also includes the prompt=login parameter to force user reauthentication if a session was already open. The user's browser made this HTTP request due to a redirect from the application. Ellipses and line breaks have been included to facilitate reading.

GET /trustedx-authserver/oauth?response_type=code&
                               client_id=demoapp&
                               scope=openid%20profile%20email&
                               prompt=login&
                               state=IxtdZtOguYVF&
                               nonce=XRoZW50aWNhd&
                               redirect_uri=https%3A%2F%2Fwww.demoapp.com%2Foauth%2Fback HTTP/1.1
Host: trustedx.demo.com:8082

Response

Once the user has been authenticated (or SSO applied), and the user has granted authorization, the application receives an HTTP GET request of the following type from the user's browser. This HTTP request is an OAuth 2.0 authorization or OpenID Connect authentication response. The application receives this request at the redirect URL specified in the authorization or authentication request message (the redirect_uri parameter of the request) or in the registered redirect URL.

GET {redirection_uri_path}?code={code}&state={state} HTTP/1.1
Host: {redirection_uri_host}

Where {redirection_uri_host}{redirection_uri_path} is the redirect URI to the application.

Parameters

Parameter

Description

code

Authorization code granted to the application for obtaining the access token and, in the case of OpenID Connect, the token ID. The authorization code generated by TRIDENT will have the length (in bytes) and expiry (in seconds) specified in the configuration of the authorization server that processed the authorization/authentication request. The client application must send the Access Token Request message to the TRIDENT before the code expires.

state

The same value that the application included in the request message.

To avoid CSRF attacks on the redirect URI, and as the standard recommends, the application must verify that the random value in this parameter (possibly along with other data) matches the value included previously in the authorization request. To know the previous value, the application retrieves it from the HTTP session it has with the browser. If the previous value is different or is not found stored in the HTTP session, the application must abort the OAuth flow (for example, indicating to the user that an invalid request was received).

Example

Below is an example of an authorization/authentication response. Ellipses have been included to facilitate reading.

GET oauth/back?code=4515...e0ba&state=IxtdZtOguYVF HTTP/1.1
Host: www.demoapp.com

Error Management

If an error occurs during the authorization phase, the TRIDENT does not return an authorization or authentication response to the application. Instead, it returns an error. In certain cases, the error is displayed directly in the user's browser.

Errors without Redirection to the Client Application

If the authorization request is invalid for any of the following reasons, the TRIDENT does not redirect the browser to the client application:

The client identifier (client_id) does not correspond to any registered client application.
The request refers to an unregistered authorization server or one that is not permitted for the client application.
An authorization server cannot be selected because the application has none associated, because none of those associated admit the scope values requested for authorization code grant, or because several do.
The request includes a redirect URL not allowed in the redirect_uri field.

In these cases, the TRIDENT displays a generic error message in the user's browser advising the user to contact the administrator. For reasons of security, no redirection to the application is performed. To diagnose this problem, the TRIDENT administrator must browse the log. In some cases, no event may be registered in the log (in this situation, the message displayed in the browser includes an error code that can be used to diagnose the problem).

Errors with Redirection to the Client Application

If the authorization request fails for another reason, for example, because the user canceled the authentication process, the TRIDENT redirects the browser to the specified redirect URI and adds in the following parameters, which are described in the standard. In this case, the client application must inform the user that an error has occurred (except where the authentication is canceled).

error: Error code. See the standard and the list below for more details.
error_description: Additional description of the error. Not required.
state: The same value that the application included in the Authorization Request message.

The following are the values supported and the meanings of error and error_description (if there is one) for some of the common errors:

invalid_request, InvalidSignIdentityTypeException: The value of the sign_identity_id parameter corresponds to a signing identity, which is not recognized because its type is undefined (identity is not certified).
invalid_request, UnrecognizedAuthnRequirementsException: None of the authentication requirements specified in the acr_values parameter are recognized.
access_denied (without error_description): The user canceled the authentication process or did not give authorization. In this case, we recommend that the client application not display any error message to the user.
access_denied, RiskyAuthnContextException: The user was denied access because they were accessing in a context of risk. This error occurs when the context analysis returns a reject result, and the authentication flow does not have a fallback for this case. Tabla
access_denied, DisabledSignIdentity: The user was denied access to the sign-on server because the requested signing identity was disabled.
access_denied, LockedSignIdentity: The user was denied access to the sign-on server because the requested signing identity was locked.
access_denied, MissingDigestsSummaryException: The user was denied access to the sign-on server because the requested signing identity's activation is using a password stored on the HSM, and either the digests_summary or the digests_summary_algorithm parameters have not been provided.
login_required: The user must be authenticated. This error can occur when the combination of authentication requirements (requested and configured) results in one or more flows of only authentication, but the user has still not started a session in the identity provider. Or when the application specifies the prompt=none parameter, but interaction with the user is required. Other related error codes are: interaction_required and consent_required. See [RSE_AUTH_INTEG] for more information.
invalid_scope: One of the scopes requested by the application is not included in the list of scopes provided by the authorization server specified in the request or has not been enabled for the authorization code grant flow. This error also occurs if the application did not request any scope and the authorization server has no default scope defined for this grant type.

In all these cases, the TRIDENT administrator can obtain details on the error from browsing the log.

Example

Below is an example of an authorization/authentication error response. Ellipses have been included to facilitate reading.

GET /oauth/back?error=access_denied&state=IxtdZtOguYVF HTTP/1.1
Host: www.demoapp.com